Games of Daze

home *** CD-ROM | disk | FTP | other *** search

/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / utils / 3dkit1 / 3dkit.doc < prev next >

Wrap

Text File | 1992-06-29 | 27.4 KB | 595 lines

TOOLS FOR 3-D WIREFRAME GRAPHICS ================================ May 1992 Hi! I have been amazed by the good reception to my 3dv wireframe viewer and by all the e-mail that it generated. My ego was sufficiently massaged to motivate me in producing a few tools for playing around with 3-D wireframe objects. These can be used in conjunction with 3dv, or on their own. 3dv allows you to display 3-D objects on a PC screen, and rotate them in real-time by moving the mouse. It can be found, for example, in the <MSDOS.GRAPHICS> directory of SIMTEL20, and in lots of other places. Look for 3DV25.ZIP (or .ZOO, etc). It is FREE, and so are the goodies contained here. Digression -- For convenience, I give here the location of free and shareware software in SIMTEL20. See SIMTEL.DOC for info on how to get it. Note that often new software versions are uploaded with slightly different names; if you don't find a file try a directory listing. There are many other archive sites in the Internet, accessible through FTP and some through e-mail servers. For example, garbo.uwasa.fi, in Finland (e-mail access instructions available by sending a 'send help' message, or a null message, to mailserv@garbo.uwasa.fi with a subject line of 'garbo-request'. Don't include the quotes ''). Much software is also available from bulletin boards. -- End of digression. 3dv uses a simple plain text file format, let's call it 3DV format, that I am taking as a common format for 3-D wireframe objects (objects formed by points and lines in three dimensions). One of the programs, 3DVto2D, does a perspective projection, like those displayed by 3dv, but with output to a file that can later be plotted, printed, or whatever. This output is an ASCII list of 2-D points (a "2D list"), that will be our common format for 2-D pictures. The idea is to have other tools that manipulate these files or convert between these and other formats, a bit like what PBMPLUS does for rasters. I have written a few of these tools, included here with C sources, to get the ball rolling. I hope that others may take over. Incidentally, the code in 3DVto2D may interest those who have asked, mostly politely (funny the attitudes of some people), for source or hints on 3-D transformations (I am not releasing the 3dv source for reasons explained in the documentation of that package). The main components of this kit are: OFFto3DV - Converts from a format called OFF (Object File Format) to 3DV. There are lots of nice 3-D objects in OFF format around the Internet. There are also around programs to convert from other formats into OFF. See OBJECTS.DOC for more info on where to find them. SHDto3DV - Converts from "shaded" format to 3DV. XYZto3DV - XYZ is an interactive 3-D editor/builder written by Dale P. Stocker to create objects for the SurfaceModel, Automove, and DKB raytracer packages. XYZto3DV (you gessed it!) converts XYZ output to 3DV format. 3DHELP - A C program written by Bruce Colletti to create 3DV files from mathematical functions. Source only, since you have to code and link your function. See 3DHELP.C for documentation. 3DMERGE - Combines two 3DV files into one. SHRINK - Minimizes the size of 3DV files. Facilitates converting objects to 3DV format; you can use a straightforward and simple-minded approach and let SHRINK to take care of efficiency. 3DVto2D - Projects a 3-D object in 3DV format into a plane, from a user-specified viewpoint. The output (2D list) can be directly displayed/printed by GNUPLOT, a free scientific graphing program (good). 2DtoHPGL - Converts a 2D list to HPGL plotter instructions. There are utilities for printing HPGL on a variety of printers, and to convert it to AutoCAD format, for example. 2DtoEXF - Converts 2D list to Evolution Computing's EXF format for EasyCAD (and presumably FastCAD). You can then use the CAD program to modify the drawing to your heart's content. The executables, for MSDOS, were compiled with Turbo C 2.0 using the compact memory model. There are also some 3-D object files (see ART.DOC), and a few example GNUPLOT scripts and DOS batch files. 3DV FILE FORMAT --------------- It is a plain ASCII text file that contains a list of point coordinates, followed by a list of move/draw instructions defining the lines in the object. It looks like this: number_of_points x1 y1 z1 x2 y2 z2 ... xn yn zn number_of_move-draws p1 c1 p2 c2 ... pm cm The xi, yi, zi are the coordinates of each point, one set to a line, separated by spaces. Each pair (pj cj) means "draw a line to point number pj using colour number cj". The point numbers are the indices (origin 1) of the points in the list of coordinates (e.g. "5" is the 5-th point in the list). The colour numbers are the usual IBM PC colour indices 1 to 15. A zero colour means "move" to the point without drawing (or drawing in the background colour, if you prefer). Multiple spaces do not matter. Coordinate values can take any form accepted by C as a floating point number, and the rest must be integers. See the included *.3DV files for examples. Actually, 3dv and some of the tools do not care about line feeds and carriage returns. However, some processing (e.g. in 3DMERGE) is easier if we always have one item per line, so let's stick to that. In retrospect, it might have been a good idea to allow for comments embedded in the file, but now it is too late. We can add anything at the end of the file, though. I suggest including there object descriptions and credits. This format is fairly compact and convenient. It is fine for wireframe objects, but of course it does not include the topological information about faces, etc., that would be needed for hidden line elimination, solid modelling, or other uses. 2D LIST FORMAT -------------- This is the output from 3DVto2D, and I propose it as a common format for two-dimensional drawings. It is simply one or more comment lines beginning with #, followed by a list of coordinate pairs and colour information, with implicit "draw" instructions and "moves" indicated by a blank line as well as a colour equal to zero: # ... x_range=[xmin:xmax] ... y_range=[ymin:ymax] ... #... xa ya ca xb yb cb ... xc yc cc xd yd cd xe ye ce ... ... xt yt ct xu yu cu xv yv cv ... xw yw cw The x and y are the coordinate values (integers or reals), and the c are colours (0 to 15). A zero colour indicates a move, and must follow a blank line; in the example, ca, cd, and cu must be zero. At least for use in 2DtoHPGL without the /s option, somewhere in the first line (comment) we must have the keywords x_range and y_range followed by bounds for the x and y values in the format shown above (see the description of 3DVto2D, below, for an example). There is no compulsory line count; the data ends with the end of file. For examples see the output generated by 3DVto2D. These files are compatible with the GNUPLOT graphing program, which can be used with its default input parameters to display or print the drawing (GNUPLOT will just ignore the third column containing the colours). GNUPLOT is free and you can find it, for example, in SIMTEL20 as <MSDOS.PLOT>GNUPLT32.ZIP . THE TOOLS IN DETAIL ------------------- Unless stated otherwise, if the names of the files to be processed are not given on the command line then the standard input/output streams are used. Thus, these tools can be used as filters, with DOS pipes or redirection. For a simple example see Xto3.BAT . Some of the tools accept optional command switches. These can go in any order, before the file names, if any. Forms different from those shown here might also work, I am not sure of the exact requirements of the public domain getopt.c that I used. In particular, you could use - as a switch character instead of /, although you might run into trouble with minus signs. Try it at your own risk. Much of this could probably have been done more elegantly (?) with AWK or SED scripts. With C, however, the tools are fast and self-contained. I wrote the code aiming at clarity ahead of efficiency. For example, I used mostly indexed arrays, instead of trying to be too clever with pointers. In the syntax, below, brackets indicate optional items. You get a similar help message by running the program with /? or other invalid arguments. OFFto3DV Syntax: OFFto3DV [/cn] [infile [outfile]] Converts infile, in OFF ASCII Indexed_Poly format, into outfile, in 3DV format. The option /cn specifies n as the colour to be used; the default is /c9. The conversion is simple-minded. Run the output through SHRINK to reduce the file size. OFF (Object File Format) objects may be specified with a set of several files. The Indexed_Poly "geometry" file, used by OFFto3DV, seems to be (almost?) always present. The convention is to use a file extension ".geom" for this, on machines that support long file extension names. Often there is also a file with extension ".aoff", that contains object information such as author, description, and copyright. There may be other files with data on colours, polygon normals, etc., which are ignored here. These objects (or at least most of them) are formed by polygons. The Indexed_Poly file is somewhat similar to a 3DV file, with a list of vertex coordinates followed by a list of polygons. The first line has three integers: the number of vertices, the number of polygons, and the total number of edges. Then comes the list of vertex coordinates, triples of floating point numbers. The polygons immediately follow, one per line. These are specified by a list of integers, where the first is the number of polygon vertices, and the others are the vertex indices in the coordinates list. See OBJECTS.DOC for sources of OFF objects, and of the full format specification if you really want it. SHDto3DV Syntax: SHDto3DV [/cn] [infile [outfile]] Converts infile, in another common object format, explained below, into outfile, in 3DV format. The option /cn specifies n as the colour to be used; the default is /c9. The conversion is simple-minded. Run the output through SHRINK to reduce the file size. I found a number of objects in this format on the Internet, for example in hanauma.stanford.edu pub/graphics/Comp.graphics/objects/3d. Initially I thought that this was OFF, and wrote this converter. It turned out that this is slightly different. In hanauma.stanford.edu pub/graphics/Comp.graphics there is a file with the famous Sutherland VolksWagen, where it is called "shaded" format, being used in a display program called "shaded" running on SUN hardware. The file contains AWK scripts to convert the original VW data from a similar but more verbose format into "shaded", and also the following note: The format for the "shaded" data files appears to be no_of_points no_of_polygons minx maxy minz maxx miny maxz x1 y1 z1 x2 y2 z2 ... xnp ynp znp no_of_corners point1 point2 point3 ... pointnc ... no_of_corners point1 point2 ... pointnc The point numbers are implicit, i.e. "5" refers to the fifth point in the list. See the file "socbal.dat" for an example. This is the same as OFF, except for the extra second line with the ranges, that we ignore, and the lack of an edges count, which forces reading all the polygons in before starting to write the move/draw instructions. XYZto3DV Syntax: XYZto3DV [infile [outfile]] XYZ2 is an interactive 3-D editor/builder written by Dale P. Stocker to create objects for the SurfaceModel, Automove, and DKB raytracer packages. XYZto3DV converts the *.3DL file produced by XYZ2 into a 3DV file. The *.3DP and *.3DS files are not needed. The conversion is simple-minded. Run the output through SHRINK to reduce the file size. XYZ2 is free and can be found, for example, in SIMTEL20 as <MSDOS.SURFMODL>XYZ21.ZIP . Other 3-D editors that might be useful for designing objects are 3DMOD (free, I found it somewhere in the Internet), and NORTHCAD (shareware, <MSDOS.CAD>NCAD3D42.ZIP in SIMTEL20). However, they do not include documentation on their file formats. 3DMOD is (C) 1991 by Micah Silverman, 25 Pierrepoint Ave., Postdam, New York 13676, tel. 315-265-7140. 3DMERGE Syntax: 3DMERGE infile1 [infile2 [outfile]] Combines two 3DV files (infile1 and infile2) into one (outfile). Note that at least one input file is required in the command line. The merging is simple-minded. Run the output through SHRINK to reduce the file size. I wrote this mainly to put together the parts of the Sutherland VW from hanauma (see above in SHDto3DV). That was a waste of time, because there was a full VW in "shaded" format somewhere else in hanauma, and in OFF format in other places. It might have other uses, though. BTW, there is an interesting photo in IEEE Computer Graphics & Applications, January 1987, p.8, showing Ivan Sutherland students digitizing the VW in 1971 using paint, measuring tape, and rulers. SHRINK Syntax: SHRINK [/on] [/tx] [/q] [infile [outfile]] This is by far the most complex program of the lot. It attempts to reduce the size of a 3DV file in three steps: 1. Checks for (nearly) duplicated points. Two points are considered the same, and one of them dropped, if the absolute differences in all the three coordinates are smaller than certain tolerance. The tolerance is calculated as the maximum coordinate range divided by x, where x is given in the /t option. The default is /t1e6. Confused? Forget it, just use the default! 2. Checks for duplicated lines, including those resulting from deleting (actually merging) points in step 1. If two lines joining the same two points have different colours, the colours are ORed. 3. Rearranges the move/draw instructions to eliminate as many moves as possible. This is a highly convoluted pointer chasing exercise, and I wont try to explain how it works. You may be able to follow the code, it is reasonably well commented. With the /o option you can restrict SHRINK to use only step 1 (/o1), 1 and 2 (/o2), or all three steps (/o3, the default). Don't ask me why. In any case "obviously" redundant moves are omitted. SHRINK can take a while on large files, so by default it outputs progress messages to the standard error stream (usually the screen). You can suppress the messages with the /q (quiet) option. This tool simplifies the writing of object generation, conversion, or manipulation procedures. Just do it the easy way, and let SHRINK take care of the efficiency aspects. 3DVto2D Syntax: 3DVto2D [/tx] [/nx] [/dx] [infile [outfile]] Now, here is the answer to all those who asked for examples of code for 3-D transformations! It is also useful for high resolution display and hard-copy. Projects in perspective a 3-D object in 3DV format into a plane, from a user-specified viewpoint. To understand the specification of the viewpoint, think of the object as enclosed by a box, and located at the centre of a sphere. The box is just large enough to contain the object, with sides parallel to the coordinate axes. The x axis goes from left to right, y from back to front, and z goes up. The box centre is at the centre of the sphere. The viewpoint can be anywhere on the sphere surface. Its location is specified by latitude and longitude in degrees, as on the surface of the Earth. Latitude goes from -90 at the South Pole, through 0 on the Equator, to 90 at the North Pole. Zero longitude is at the front, increasing to the right; you can use any positive or negative number which is interpreted modulo 360, i.e., plus or minus 360 degrees brings you back to the front of the sphere. This is the same system used in 3dv, where you move around the object by changing longitude with left-right mouse movements, and latitude by moving up-down. You can use 3dv to choose a good viewpoint, noting the displayed latitude/longitude values. The /t option specifies the viewpoint laTitude, and /n the loNgitude. The defaults are zero. For example, 3DVto2D /t33.3 /n-60 thingy.3dv thingy.2d would produce a view from a point at latitude 33.3 degrees (North) and longitude -60 degrees (60 degrees West). The /d option can be used to give the viewpoint distance, i.e. the sphere radius. A positive value is an absolute distance in user units, that is, in the same units used for the points coordinates. A /d0 is equivalent to an infinite distance or, in other words, produces an orthogonal projection (no perspective). A minus sign indicates a multiple of the longest diagonal of the bounding box (plus 1%, for compatibility with 3dv). The default is /d-3, identical to 3dv. The output image is in 2D list format and, as already mentioned, can be directly displayed/plotted/printed with GNUPLOT, or converted to other formats. The data is scaled is such a way that the image fits into a square with corners (-1,-1) and (1,1), with the object bounding box centre mapped into (0,0). Some information is included in two lines of comments at the beginning of the file, like this: # n=438 scale=43955.7 x_range=[-0.589757:0.432624] y_range=[-1:0.97761] # latitude=33.3 longitude=-60 distance=367590 In this example 438 is the number of points in the file, and 43955.7 is the scale factor that would restore the original object dimensions. As mentioned before, x_range and y_range gives the extent of the image along the x and y axes, and may be used by 2DtoHPGL. The second line contains the transformation details, with the viewpoint distance in absolute user units. Hints for using GNUPLOT. For best results you need to adjust the aspect ratio to 1:1 with the "set size" command. With my monitor and Trident 8900 card, I found by trial-and-error that "set size 0.82,1" and "set size 0.83,1" worked well for the standard VGA and for the SVGA 1024x768 modes, respectively. For the HP DeskJet printer at 150 dpi, "set size 1.09,1" was best. See the file "3D" for the GNUPLOT commands that you might need to use. Better, edit that file if necessary, and display your 2D list by entering "GNUPLOT", followed by "LOAD '3D'". The file "DJ" is an example for printer output on the DeskJet. After displaying with 3D, you could enter "LOAD 'DJ'", and "REPLOT". An interesting use of 3DVto2D would be for producing stereograms (stereo pairs or anaglyphs). Just make two views with latitude zero and slightly different longitudes. A difference of 4 to 7 degrees is generally recommended. Exactly how to go about it for display/hardcopy/viewing is left as an exercise for the reader. Answers to some Frequently Asked Questions: The computations in 3dv are essentially as in 3DVto2D, but using integer arithmetic for speed. The trick is to scale the values appropriately at the right places by factors high enough to maintain precision, but not as high as to overflow the 16-bit integers. Easier said that done, but not that difficult, really. The precision achieved was better than the 256x192 resolution of my home-made graphics card for the TRS-80 in the original implementation. It is somewhat lower than EGA/VGA, though, and you may notice that sometimes points jump around a bit. If you want to be elitist, the 32-bit integers on 386 processors would be more than enough. And NO!, I am not releasing the source of 3dv, it is too ugly. My original source for 3-D transformations was probably Ahuja, D.V., and Coons, S.A. "Geometry for construction and display". IBM Systems Journal 7,188-205. 1968. (showing my age again!). This is pretty good and still interesting, especially the use and explanation of homogeneous coordinates. Nowadays you can probably find these things in most Computer Graphics textbooks. Here goes a list, together with a somewhat concise (!) explanation, from the "Frequently Asked Questions" file in the Internet/USENET comp.graphics Newsgroup: 1) General references for graphics questions: Computer Graphics: Principles and Practice (2nd Ed.), J.D. Foley, A. van Dam, S.K. Feiner, J.F. Hughes, Addison-Wesley 1990, ISBN 0-201-12110-7 Principles of Interactive Computer Graphics (2nd Ed.), Newman and Sproull, McGraw Hill, ISBN 0-07-046338-7 Procedural Elements for Computer Graphics, David F. Rogers, McGraw Hill, ISBN 0-07-053534-5 Mathematical Elements for Computer Graphics 2nd Ed., David F. Rogers and J. Alan Adams, McGraw Hill, ISBN 0-07-053530-2 Applied Concepts in Microcomputer Graphics, Bruce Artwick, Prentice-Hall, ISBN 0-13-039322-3 Digital Picture Processing, vols. 1&2, Azriel Rosenfeld and Avi Kak, Academic Press 1976 Three Dimensional Computer Graphics, Alan Watt, Addison-Wesley, ISBN 0-201-15442-0 An Introduction to Ray Tracing, Andrew Glassner (ed.), Academic Press 1989, ISBN 0-12-286160-4 Graphics Gems, Andrew Glassner (ed.), Academic Press 1990, ISBN 0-12-286165-5 Graphics Gems II, James Arvo (ed.), Academic Press 1991, ISBN 0-12-64480-0 2) Drawing three-dimensional objects on a two-dimensional screen. The simple answer is, you divide by the depth. For a more verbose explanation, see any of the above references. Well... that's all I know! 2DtoHPGL Syntax: 2DtoHPGL [/s] [/xn] [/yn] [/wn] [/hn] [/pn] [infile [outfile]] Converts a 2D list to HPGL (Hewlett Packard Graphics Language) plotter instructions. HPGL (alias IBM-GL, RD-GL, etc.) is used by many plotters, and is emulated on printers such as our IBM 4029 laser. The PCL5 language used by the latest HP printers includes HPGL as a subset. There are also software HPGL emulators for other devices, discussed below. If the /s option is not specified, x_range and y_range information is expected in the file and used to scale the drawing up to the limits of the plotting area (with the HPGL IP and SC instructions). If /s is given, it is assumed that the data fits into a square bounded by -1 and +1 (see 3DVto2D, above), and the scaling fits this square to the plotting area (useful for making stereograms, for example). In both cases the aspect-ratio is preserved. The /x and /y options can be used to specify the x and y coordinates of the centre of the plotting area, in plotter units. On most (all?) plotters a plotter unit is 25 microns (40 units/mm). The default /x5450 and /y3825 corresponds to the centre of an A4 sheet (ISO standard, used in civilized countries). For centring on US size A (letter) paper use /x5150. The maximum size of the plotting area can be given with /w (width) and /h (height). The defaults /w10000 and /h7200 will normally use most of the available space with both types of paper. More specifically, on the HP small plotters x goes from 0 to 10300 with size A paper, and to 10900 with A4, while y goes from 0 to 7650 with both. A string of up to 15 digits can be given with the /p option to change the mapping from colour indices to pen numbers. The default is /p123456781234567. Only very basic HPGL instructions are used: DF (defaults), IP (input scaling points), SC (scale), SP (select pen), PU (move with pen up), and PD (draw with pen down). Therefore, compatibility problems should be unlikely (really!). Apart from plotters and laser printers, there is a number of HPGL emulators. PRINTGL (shareware, US$40, <MSDOS.PLOT>PRTGL118.ZIP in SIMTEL20) is excellent, working with all sort of graphic cards and printers (it can also produce PCX raster files). See DJPLOT.BAT for an example of coaxing the PaintJet driver in PRINTGL to print on the DeskJet 500C colour printer (with A4 paper). Yes, I know, it looks horribly complicated; don't worry, PRINTGL has also an easy-to-use menu driven front end. A similar program is SPLOT ("nagware", US$70, <MSDOS.GRAPHICS>SPLT244.ZIP), which can also convert to AutoCAD DXF format. HPGL2PS (<MSDOS.POSTSCRIPT>HPGL2PS.ZIP) produces output for Postscript printers, is free, and includes C source. Also free and with source included is <MSDOS.AUTOCAD>HPGL2SCR.ZIP, a program to convert HPGL to AutoCAD DXF. Two free HPGL pre-viewers (screen output only), including source code, are found in SIMTEL in <MSDOS.GRAPHICS>SHOWGL15.ZIP (written in C), and <MSDOS.GRAPHICS>HPGLVU10.ZIP (Pascal). Unfortunately, no free HPGL to (non-Postscript) printer output seems to be available. It would not be too difficult, though, to modify the SHOWGL, HPGLVU, or HPGL2PS code, perhaps using the BGI printer drivers in <MSDOS.BORLAND>PRBGI094.ZIP (Hint! Hint!). Another alternative would be to use HPGL2PS together with the Ghostscript Postscript emulator (available in the SIMTEL <MSDOS.POSTSCRIPT> directory). 2DtoEXF Syntax: 2DtoEXF [infile [outfile]] EasyCAD is a neat little CAD program, produced by Evolution Computing, that used to come bundled with the MicroSoft mouse. BTW, I believe in "small is beautiful", and dislike monsters such as AutoCAD, Mathematica (use DERIVE instead!), and MS Windows. Anyway, EasyCAD has a CONVERT utility that can convert EasyCAD's binary .DWG files to and from ASCII .EXF (Exchange File Format) files (and also to and from AutoCAD .DXF files). 2DtoEXF converts 2D lists into .EXF files. I believe that Evolution computing also makes another system called FastCAD, that presumably also accepts EXF. 2DtoEXF does not use any of the information (x_range, etc) in the initial comment lines of the 2D file. After converting to .DWG, you can use EasyCAD for editing (e.g. adding text, erasing hidden lines, etc.), and/or plotting/printing. See the description of 2DtoHPGL above for conversion to AutoCAD or other systems accepting DXF. LEGAL TRIVIA, ETC. ------------------ You can do whatever you like with all this (just like that!). I thought hard about placing copyright notices everywhere, having read horror stories about people stealing public domain software and restricting its use by others. Finally decided against it, for no good reason, really. I just did not feel like adding to what is hopefully no more than generalized paranoia. If I am wrong, the world will just have to learn to survive without these earth-shattering pieces of software. Anyway, if you get rich with this without giving me my part of the booty I wish you burn in Hell, your yacht sinks, and the IRS investigates you. I also gather that, because of a lawyers infestation somewhere, I am supposed to say things like that I am completely irresponsible (a well known fact), that this software is not guaranteed to improve your sex life (or your money back), that IBM is a registered trademark of IBM, etc. Whatever. Lawyers: I am a fair distance away, and I have no money (er... umm... don't take it as a challenge, guys!). After writing this, Keith Petersen asked me that if I include here the SIMTEL.DOC file "Please make it clear that SIMTEL20 has no connection with your product and does not endorse it" (see what I mean?). SIMTEL20 HAS NO CONNECTION WITH MY PRODUCT, AND DOES NOT ENDORSE IT :-) . By the way, my employer had nothing to do with this either. Here goes my home address until August 1992 or so. I am moving but I don't know where yet. My e-mail address will probably change sooner than that, and I may temporarily lose Internet access at any moment. Oscar García 1 Clyde Street Rotorua New Zealand Internet: garciao@mof.govt.nz